home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 22 / Cream of the Crop 22.iso / os2 / bbs2web.zip / BBS2WEB.TXT < prev    next >
Text File  |  1996-11-03  |  19KB  |  417 lines
  1.  
  2.                               Bbs2Web Version 1.07
  3.                 Html Web Page Generator for Maximus BBS Systems
  4.                                3rd November 1996
  5.  
  6.          (C) Copyright 1996 by CodeLand Australia, All Rights Reserved
  7.                              Written by Colin Wheat
  8.  
  9.                                colinw@ami.com.au
  10.                              http://www.ami.com.au
  11.                               ftp://ftp.ami.com.au
  12.                               3:690/613.0@fidonet
  13.  
  14.  
  15.  
  16.     INTRODUCTION
  17.     ────────────────────────────────────────────────────────────────────────
  18.     Bbs2Web is a simple web page generator for an OS/2 Maximus BBS
  19.     system's file base. If it works for you, that's great. If not than
  20.     I'm interested in hearing about it. I can't promise fixes or ongoing
  21.     support, but assuming your problem may also turn up here on my
  22.     system, it's possible I'll fix it for a subsequent version.
  23.  
  24.     As usual with Shareware and Freeware releases, there are no
  25.     guarantees with this software. User beware, use it at your own risk.
  26.  
  27.  
  28.  
  29.     REQUIREMENTS
  30.     ────────────────────────────────────────────────────────────────────────
  31.     1) OS/2 2.1 or above, WARP V4 (Merlin) recommended. OS/2 V2.1 and
  32.     WARP would also require TCP/IP V2 with the suitable CSD's
  33.     installed.
  34.  
  35.     2) An HPFS partition to hold the generated output *.html files.
  36.     Bbs2Web supports the nested Maximus V3.XX file area groups. For
  37.     nested area output, files with long file names will be generated.
  38.     E.g. "Os2.Network.Tcpip.Html". This is a design feature which
  39.     cannot be changed.
  40.  
  41.     3) An OS/2 httpd (WEB) server. IBM Internet Connection Server
  42.     (ICS) is highly recommended.
  43.  
  44.     4) A suitable server for file serving. Files can be served by the
  45.     httpd server, but you may prefer to install an ftpd server for the
  46.     purpose.
  47.  
  48.     5) An active and working Maximus V3.XX OS/2 BBS file base. Maximus
  49.     is the most popular OS/2 BBS package available. Note that it may
  50.     be possible to modify a Max V2.xx system to successfully support
  51.     Bbs2Web operation.
  52.  
  53.     6) An active realtime 24hr internet link. The author operates via
  54.     a dedicated V34 modem link, anything as fast or faster would do
  55.     fine. Note that for intranet operation this is not requirement.
  56.  
  57.  
  58.  
  59.     FEATURE SUMMARY
  60.     ────────────────────────────────────────────────────────────────────────
  61.     Bbs2Web generates a full set of Web pages representing a Maximus
  62.     V3.xx file base. It includes support for file groups by building
  63.     nested pages. CDROM file areas are supported, and can be excluded
  64.     from the output pages. Download links are automatically placed in
  65.     the output pages for every listed file. Files can be downloaded by a
  66.     suitable server, usually either httpd or ftpd. This is controlled by
  67.     the configuration file FileLinkPath statement. File areas can be
  68.     excluded from the output by priviledge setting, using the
  69.     configuration file ListPrivBelow statement. Bbs2Web also includes a
  70.     file base search engine, MaxFind.Exe. All generated pages include a
  71.     file name search entry form and a matching call to MaxFind.Exe via
  72.     the Search button. MaxFind.Exe should be copied to your web server's
  73.     cgi-bin sub-directory. Note that MaxFind.Exe also -needs- an
  74.     environment variable set, to allow it to find the configuration
  75.     file.
  76.  
  77.     MaxFind.Exe environment variable setting example:
  78.     SET BBS2WEB_INI=f:\bin\bbs2web.ini
  79.  
  80.  
  81.  
  82.     DISTRIBUTION FILES
  83.     ────────────────────────────────────────────────────────────────────────
  84.     BBS2WEB.EXE     -   The Web page compiler
  85.     BBS2WEB.INI     -   Compiler configuration text file
  86.     MAXFIND.EXE     -   The Maximus 3.XX file base search engine
  87.     BBS2WEB.TXT     -   This documentation
  88.     INDEX.HTM       -   Example Bbs2Web generated Web page from the
  89.                         author's system
  90.     BBS2WEB.GIF     -   Example background image for generated pages
  91.     MASTBBS.GIF     -   Example masthead image for generated pages
  92.  
  93.  
  94.  
  95.     THE CONTROL FILE BBS2WEB.INI
  96.     ────────────────────────────────────────────────────────────────────────
  97.     [BBS2WEB]
  98.     Denotes the start of data within the configuration file. Data is
  99.     read from the configuration file beginning from the line following
  100.     the [BBS2WEB] entry, and continues until a token beginning with a
  101.     '[' character (e.g. [END]).
  102.  
  103.     ;-MAXIMUS--------------------------------------------------
  104.  
  105.     MaxPath=F:\Bbs
  106.     The Maximus directory. Several files are assumed to exist in this
  107.     directory, including Farea.Dat and Maxfiles.Idx.
  108.  
  109.     AreaDatFile=Farea.Dat
  110.     The name of the Maximus V3.xx file area data file, usually found
  111.     in the Maximus directory. Bbs2Web will look for this file at the
  112.     MaxPath path, see below.
  113.  
  114.     IncludeCdrom=Yes
  115.     A flag to control the including or excluding of CDROM file areas
  116.     for the output pages.
  117.  
  118.     ListPrivBelow=Extra
  119.     File areas will only be included in the output pages when holding
  120.     a priviledge less than the ListPrivBelow setting. File area
  121.     priviledge levels are set in your Maximus FIlearea.Ctl control
  122.     file. Note that Bbs2Web currently has NO support for override
  123.     locks and levels.
  124.  
  125.     ListKeyAreas=No
  126.     Bbs2Web supports only the standard Maximus priviledge levels, and
  127.     does not support extended priviledges. "Normal" is a valid
  128.     priviledge verb, "Normal/1" (note the Key extension) is not.
  129.     Unknown priviledge strings are assigned a "Hidden" (65535)
  130.     priviledge value so that such areas will not appear in the
  131.     generated output. ListKeyAreas=No is the default operation.
  132.     ListKeyAreas=Yes instructs Bbs2Web to trim "/" extensions from
  133.     priviledge strings prior to further processing. This would for
  134.     example convert "Normal/1" to "Normal" thus allowing areas thus
  135.     marked to appear in the output listings. The effect is to ignore
  136.     Key extensions in your file areas.
  137.  
  138.     ;-HTML CONTENT---------------------------------------------
  139.  
  140.     BackGroundImage=/bbs/Bbs2Web.Gif
  141.     An optional page background bitmap image, used on all output
  142.     pages.
  143.  
  144.     HtmlTitle=The_Library_Network_BBS
  145.     The Web page system title. Underscore characters are converted to
  146.     space characters.
  147.  
  148.     HtmlMast=/bbs/MastBbs.Gif
  149.     An optional masthead image, that replaces the HtmlTitle heading on
  150.     generated pages.
  151.  
  152.     HtmlHeading=BBS_File_Areas
  153.     The Web page sub-heading. Underscore characters are converted to
  154.     space characters.
  155.  
  156.     ReturnLinkTitle=The_Library_Network
  157.     The title for a link pointing the browsing user back to your site
  158.     home page or equivalent. Underscore characters are converted to
  159.     space characters.
  160.  
  161.     ReturnLinkPath=http://www.ami.com.au/
  162.     A link entry for the master Web page, pointing the browsing user
  163.     back to your site home page or equivalent.
  164.  
  165.     NoSearch=No
  166.     Bbs2Web defaults to adding a search form to every generated page.
  167.     NoSearch=Yes disables the search form, Bbs2Web does not include
  168.     the form on generated pages.
  169.  
  170.     CgiSrvrPath=http://www.ami.com.au/cgi-bin/maxfind.exe
  171.     The CGI search engine full URL path and name.
  172.  
  173.     ;-HTML GENERATION------------------------------------------
  174.  
  175.     HtmlFile=index.html
  176.     The name of the generated master Web page. All other pages are
  177.     linked from this page, or from pages linked from this page,
  178.     recursively.
  179.  
  180.     HtmlPath=f:\bbs\html\
  181.     The path for the generated Web page files. You should create a
  182.     sub-directory for this purpose. On the author's system, the
  183.     Bbs2Web output Web pages total 438 files and !6.2 Megabytes of
  184.     text/html data files.
  185.  
  186.     FileLinkPath=ftp://bbs.ami.com.au/pub/
  187.     The file download link path. Bbs file paths and names will be
  188.     appended to this entry, for creation of the on page download link.
  189.     You can send the files to the user via various servers, including
  190.     httpd, and ftpd. Here's an example for a httpd served file for the
  191.     author's system; "http://bbs.ami.com.au/pub/". Note that you'll
  192.     need to setup your server to allow access to the file base.
  193.     Bbs2Web filters out drive names from the Maximus supplied file
  194.     download paths. See also the MapDrive command.
  195.  
  196.     MapDrive=j: /hobbes1/
  197.     Multiple MapDrive verbs can be listed, to a maximum of 16. Bbs2Web
  198.     will convert a MapDrive listed drive letter or initial path to the
  199.     supplied path, for the output page links. This is probably a
  200.     required function for most systems. I've not considered the
  201.     situation in depth, only that it's required here. Let me know if
  202.     you're unable to fully serve your file base with the existing
  203.     Bbs2Web features.
  204.  
  205.     [END]
  206.     Denotes the end of Bbs2Web data within the control file. This verb
  207.     is optional, end of file will also terminate control file data
  208.     loading.
  209.  
  210.  
  211.  
  212.     FILE SERVING
  213.     ────────────────────────────────────────────────────────────────────────
  214.     Setting up the file server and arranging for Bbs2Web to correctly
  215.     build working file links in the output pages, is probably the
  216.     largest part of the Bbs2Web installation task. :) I've attempted
  217.     to clearly explain the control file verbs usage above, with the
  218.     verbs FileLinkPath and MapDrive both directly affecting file serving.
  219.     Rather than attempting an in depth discussion, I'll now provide an
  220.     example of the working setup here, the environment in which and
  221.     for which Bbs2Web was written.
  222.  
  223.     Bbs2Web finds the Maximus files by firstly reading the Farea.Dat
  224.     file in the Maximus directory. From this file it's able to build a
  225.     list of downloadable file areas.
  226.  
  227.     Here's one of the Maximus file areas on the system here, as
  228.     represented in Filearea.Ctl. Farea.Dat is compiled from
  229.     Filearea.Ctl, subject to specific Maximus configuration.
  230.  
  231.     FILEAREA LOCAL
  232.             ACS             Disgrace
  233.             DESC            System Utilities & Information
  234.             DOWNLOAD        H:\General\Newuser
  235.             UPLOAD          H:\Upload
  236.             % FILELIST        <file>
  237.             % OVERRIDE        FILE File_Download Normal
  238.             % TYPE            <Slow> <Staged> <NoNew> <CD>
  239.             % MENUNAME        <OldName> <NewName>
  240.     END FILEAREA
  241.  
  242.     The relevant entry is the file download path,
  243.     "H:\General\Newuser".
  244.  
  245.     Having build a list of downloadable file areas, Bbs2Web accesses
  246.     the data files (FILES.IDX/DAT/DMP) within each directory, to
  247.     compile and generate the output Web pages. A Maximus V3.xx system
  248.     uses the FILES.BBS text file as the master for the directory
  249.     listing, so you'll want to run the file base compiler (fbp)
  250.     -before- Bbs2Web is run, usually during nightly maintenance. We're
  251.     ignoring CDROM areas in this simple explanation, for those areas
  252.     the data files are actually found on the FILELIST path.
  253.  
  254.     So far that's not too difficult :). The problems begin to appear
  255.     though when attempting to build a working download file link for
  256.     each listed file. From the example above, we have a Maximus
  257.     supplied path of "H:\General\Newuser". On the system here, I use
  258.     the Toronto File System (TVFS) to build a ftp downloadable single
  259.     drive representation of the complete BBS file base, itself spread
  260.     across multiple server drives. The corresponding TVFS path is;
  261.     "T:\pub\general\newuser". The ftp server is setup with a home
  262.     directory of "T:\", so that a base ftp login shows the "\pub"
  263.     directory available from root.
  264.  
  265.     For any one file from our example directory, say "LIBRARY.LZH",
  266.     using a Bbs2Web FileLinkPath of "ftp://bbs.ami.com.au/pub/", and a
  267.     file area path from Maximus of "/General/Newuser" (Bbs2Web
  268.     converts '\' characters to '/' for the purpose of link creation),
  269.     the resulting Web page listed file link becomes
  270.     "ftp://bbs.ami.com.au/pub/general/newuser/LIBRARY.LZH".
  271.  
  272.     The MapDrive verb becomes useful (essential) for Maximus file
  273.     paths that are mapped back to the one virtual drive for server
  274.     usages such as ftp. As a short example; a CDROM file on the BBS
  275.     has a path of "J:\Bbs\MAX300C.ZIP". For ftp server usage, that
  276.     path is mapped by TVFS to "T:\pub\hobbes1\bbs\MAX300C.ZIP". With a
  277.     MapDrive setting of "MapDrive=j: /hobbes1/" and by converting the
  278.     '\' characters to '/' characters, the file path becomes
  279.     "/hobbes1/Bbs/MAX300C.ZIP". With the addition of the FileLinkPath
  280.     setting, the full file link is
  281.     "ftp://bbs.ami.com.au/pub/hobbes1/Bbs/MAX300C.ZIP".
  282.  
  283.  
  284.  
  285.     THE SEARCH ENGINE
  286.     ────────────────────────────────────────────────────────────────────────
  287.     The search engine MaxFind is a html CGI server utility. It should
  288.     be moved to your Web server cgi-bin directory. Standard cgi usage
  289.     uses program command line and stdout for remote communication, so
  290.     configuration information is usualy passed via environment
  291.     variables. In fact the Web server also passes the user's search
  292.     request data to MaxFind via environment variables in this case.
  293.     MaxFind uses methods and code similar to Bbs2Web to access the
  294.     Maximus file bases. It's able to operate soley on the information
  295.     contained within Bbs2Web.Ini. The one configuration requirement
  296.     then, is to pass it the full path and name of the Bbs2Web.Ini
  297.     configuration file. This is accomplished by the BBS2WEB_INI
  298.     environment variable.
  299.  
  300.     e.g. SET BBS2WEB_INI=f:\bin\bbs2web.ini
  301.  
  302.     This must be placed in the OS/2 system CONFIG.SYS file.
  303.  
  304.     Technically, MaxFind uses a sub-string single key search, across
  305.     all BBS listed file bases. This may be subject to enhancement in
  306.     later versions of the program. Access restrictions identical to
  307.     Bbs2Web apply to the resulting output.
  308.  
  309.  
  310.  
  311.     VERSION CHANGES
  312.     ────────────────────────────────────────────────────────────────────────
  313.     V1.00 - Released 96-03-24.
  314.             The initial public release.
  315.  
  316.     V1.03 - Released 96-10-04.
  317.             Minor code changes and bug fixes. Fixed a problem with
  318.             html tokens in the file description fields, where too
  319.             many '<' or '&' characters in the description field would
  320.             overflow allocated storage.
  321.  
  322.     V1.04 - Released 96-10-09.
  323.             Modified the MapDrive INI verb to support a partial path.
  324.             The original design supported only drive letters. Changed
  325.             the Maximus file area access support to allow and use the
  326.             new Max V3 verbs. Bbs2Web was using the old V2 verbs
  327.             (Twit) etc. Opps.
  328.  
  329.     V1.05 - Released 96-10-10.
  330.             Added a new INI verb, CgiSrvrPath. CgiSrvrPath supplies
  331.             the full URL path and name of the CGI search engine,
  332.             usually MaxFind.Exe. Previously the search engine path was
  333.             generated from the ReturnLinkPath URL.
  334.  
  335.     V1.06 - Released 96-10-29.
  336.             Adjusted the area priviledge verb lookup function, to
  337.             correctly supply caller nominated default responses for
  338.             unknown verbs. Bbs2Web does not yet support keys in the
  339.             privil verbs, so that an access level of "Normal/1" is an
  340.             unknown verb. Bbs2Web will now set area/file priviledge
  341.             levels to HIDDEN for unknown verbs, and the INI's
  342.             ListPrivBelow setting to TRANSIENT for unknown privil verbs.
  343.             This should stop Bbs2Web displaying files or areas which
  344.             have unknown privil levels attached.
  345.  
  346.             Added new INI verb, "ListKeyAreas". ListKeyAreas defaults
  347.             to off (No). When activated (ListKeyAreas=Yes), ListKeyAreas
  348.             will instruct Bbs2Web to mask all key additions to priviledge
  349.             strings. E.g. "Normal/1" would be translated to "Normal".
  350.             The default action (ListKeyAreas=No) is to use privil
  351.             verbs as supplied, and Bbs2Web does NOT support keys.
  352.  
  353.             Added a new INI verb, "BackGroundImage". E.g.
  354.             BackGroundImage=/bbs/Bbs2Web.Gif
  355.             BackGroundImage activates a background image file for
  356.             the Bbs2Web generated html pages. The image file should
  357.             be copied to a server accessable path, and a matching
  358.             URL listed with the BackGroundImage verb. On the author's
  359.             system the image file exists in the html output directory.
  360.             Note that the background image is used by both Bbs2Web and
  361.             MaxFind.Exe. BBS2WEB.GIF was also added to the distribution
  362.             archive.
  363.  
  364.     V1.07 - Released 96-11-03.
  365.             Fixed a problem with MaxFind, concerning string termination
  366.             for the file name field within the FIDX structure used by
  367.             MAXFILES.IDX. This should fix some problems with the
  368.             search engine.
  369.  
  370.             Add new INI verb, NoSearch. With NoSearch=Yes, Bbs2Web
  371.             does not include the search form on the generated html
  372.             pages.
  373.  
  374.             Added new INI verb, HtmlMast. HtmlMast supplies the URL of
  375.             and optional page masthead image. This replaces the
  376.             HtmlTitle heading. Example: HtmlMast=/bbs/MastBbs.Gif
  377.  
  378.             Fixed a problem with priviledge value comparisons.
  379.             Priviledge values are now stored as unsigned values.
  380.  
  381.  
  382.  
  383.     FEEDBACK
  384.     ────────────────────────────────────────────────────────────────────────
  385.     Mail me a note at colinw@ami.com.au if you've found Bbs2Web useful
  386.     on your system, or if you find problems with it's usage. Call by
  387.     http://www.ami.com.au/bbs to see a working example.
  388.  
  389.     My interest at this time especially, is to use and push OS/2 to
  390.     the limit with internet and tcp/ip usage. OS/2 is indeed an
  391.     excellent product :). IBM's years of OS/2 support and development
  392.     are bound to have major repercussions into the next decade, the
  393.     writing is on the wall. This especially true now in the
  394.     home/office and consumer markets, given MS's dismal longterm
  395.     performance in the OS arena, not the least recently with the
  396.     slightly sad and disappointing WIN3.XX upgrade, the predominately
  397.     16bit WIN95. With MS's own product life projection of 3yrs or
  398.     less, Win95 has NO future even now shortly after it's (much
  399.     belated) launch. With the need for stable 32bit OS's for the lead
  400.     into the next centuary, OS/2 and it's future relatives are looking
  401.     increasingly inviting to a great many people. If you haven't yet
  402.     tasted real 32bit power on your desktop, run don't walk to your
  403.     local OS/2 specialist and order your copy of the future now :).
  404.  
  405.     For Australian residents; Amisoft Computers can supply all your
  406.     OS/2 hardware and software needs. Call them at (09) 293-3278
  407.     regarding your requirements..
  408.  
  409.     IBM OS/2 WARP V4.0 (Upgrade Version) $199.00
  410.     IBM OS/2 WARP V4.0 (FullPack Version) $299.00
  411.  
  412.     Regards,
  413.     Colin Wheat.
  414.  
  415.     ────────────────────────────────────────────────────────────────────────
  416.  
  417.